home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / PROTO212.ARJ / PROTOF.MAN < prev    next >
Text File  |  1992-01-14  |  55KB  |  1,365 lines
  1.  
  2.  
  3. 1        Introduction et avertissements                                    1
  4. 1.1      Pourquoi utiliser un extracteur                                   1
  5. 1.1.1    Mise en service d'une librairie avec prototypes invalides         1
  6. 1.1.2    Validation implicite du fichier d'inclusion                       1
  7. 1.1.3    Révision des clients d'un service                                 2
  8. 1.2      Certains compilateurs peuvent extraire les prototypes             2
  9. 1.2.1    Un compilateur peut oublier des prototypes                        2
  10. 2        Limites de la version d'évaluation                                2
  11. 2.1      Production automatisée de sommaire alphabétique                   3
  12. 2.2      Production d'un index permuté                                     3
  13. 2.3      Production et entretien d'un historique des fonctions             3
  14. 3        Spécifications et opération                                       3
  15. 3.1      Principes généraux                                                4
  16. 3.1.1    Systèmes, clients, et fournisseurs en programmation               4
  17. 3.1.2    Déclaration de fonction (prototypes) et définition                4
  18. 3.1.2.1  Utilité des déclarations de fonctions                             5
  19. 3.1.2.2  Stratégie d'utilisation des prototypes                            5
  20. 3.1.2.3  Composition du fichier d'inclusion                                5
  21. 3.2      ANSI C et C++ supportés                                           6
  22. 3.3      Mot-clés ajoutés pour automatiser l'opération de                  6
  23.          l'extracteur                                                
  24. 3.3.1    Définition des mots clés supplémentaires                          6
  25. 3.4      Options de la ligne de commande                                   6
  26. 3.4.1    @fichier : fichier contenant des paramètres de ligne de           7
  27.          commande                                                    
  28. 3.4.1.1  Exemple de localisation de fichiers de commandes                  7
  29. 3.4.1.2  @ spécifié sans fichier                                           8
  30. 3.4.2    -a : Accès par défaut au fonctions membres (C++)                  8
  31. 3.4.3    -b : Mise à jour d'un fichier C++ à partir d'un fichier .pm       8
  32. 3.4.3.1  Exemple d'utilisation de l'option -b                              9
  33. 3.4.3.2  Controle de la distribution des prototypes de fonctions           9
  34.          membres                                                     
  35. 3.4.4    -c : composition de l'extraction                                  9
  36. 3.4.4.1  Le verbe export : extension au C                                 10
  37.          Ajout du verbe export au langage C                               10
  38.          Utilité du verbe export                                          10
  39.          Le verbe _export                                                 10
  40. 3.4.4.2  Combinaison de l'option -c et -f dans une seule session          11
  41. 3.4.4.3  Paramètre 'i' de l'option -c: Référence inverse                  11
  42. 3.4.4.4  Paramètre 'd' de l'option -c: Prototypes et documentation        11
  43. 3.4.4.5  Corrections au prototypes avant la génération                    11
  44.          Fonctions sans type de retour                                    12
  45.          Paramètres sans type                                             12
  46.          Fonctions sans paramètre                                         12
  47. 3.4.5    -C : Ne traite pas les commentaires imbriqués                    12
  48. 3.4.6    -d : Définition de symbole sur la ligne de commande              12
  49. 3.4.7    -e : Ferme un fichier résultat                                   13
  50. 3.4.7.1  Protection contre le double traitement durant une session        13
  51.          Fichiers sources répartis dans deux répertoires                  13
  52. 3.4.8    -f/+f : identification d'un fichier résultat                     13
  53. 3.4.8.1  Combinaison de l'option -c et -f dans une seule session          14
  54. 3.4.9    -h : fichier de prototypes C++ à décomposer                      14
  55. 3.4.10   -i : Mode incrémental                                            14
  56. 3.4.11   -I : Répertoire de recherche pour les fichiers d'inclusion       15
  57. 3.4.12   -k : Renomme les mot-clés reconnus par l'extracteur              15
  58. 3.4.13   -l : Spécification d'un nom alternatif pour l'option -h          15
  59. 3.4.14   -m : Sélectionne une méthodologie particulière                   16
  60.  
  61.  
  62.  
  63.                                                               1
  64.  
  65.  
  66. 3.4.14.1 Répertoires alternatifs pour l'exportation des fichiers          16
  67.          résultat                                                    
  68. 3.4.15   -o : Nom alternatif pour l'option -m                             16
  69. 3.4.16   -p : Activation de l'extraction pour les fichiers suivants       16
  70. 3.4.16.1 Exemple d'utilisation des options -x et -p                       16
  71. 3.4.16.2 Protection contre le double traitement durant une session        17
  72. 3.4.17   -P : activation du préprocesseur                                 17
  73. 3.4.17.1 Traitement des #define même lorsque le préprocesseur n'est       17
  74.          pas actif                                                   
  75. 3.4.17.2 Traitements des #if, #ifdef, ... sans -P                         17
  76. 3.4.18   -s : opération silencieuse                                       18
  77. 3.4.19   -t : lecture du source à traiter sur la console                  18
  78. 3.4.20   -v : Liste des fichiers traités                                  18
  79. 3.4.21   -x : exclusion d'un groupe de fichier                            18
  80. 3.4.21.1 Exemple d'utilisation des options -x et -p                       18
  81. 3.4.21.2 Protection contre le double traitement durant une session        18
  82. 3.4.22   Macros et Caractères spéciaux                                    19
  83. 3.4.22.1 $ : Nom du répertoire courant                                    19
  84. 3.5      Combinaisons invalides d'options                                 19
  85. 3.6      Stratégie d'utilisation de l'extracteur                          19
  86. 3.6.1    Convention d'utilisation: Avertissement au lecteur               19
  87. 3.6.2    Le répertoire (directory) est la base de l'organisation d'un     19
  88.          système                                                     
  89. 3.6.3    Convention de noms pour les fichiers d'inclusion                 20
  90. 3.6.4    Fichiers générés localement                                      20
  91. 3.6.5    Fichiers exportés pour les clients                               20
  92. 3.6.5.1  Le verbe export : extension au C                                 21
  93. 3.6.6    Unicité du fichier d'inclusion                                   21
  94.  
  95.  
  96.  
  97. 1        Introduction et avertissements                              
  98.  
  99.     L'extracteur de prototypes automatise et agrémente une 
  100.     partie du travail d'un programmeur en langage ANSI C et C++ 
  101.     2.0. Il supporte aussi la syntaxe de déclaration de 
  102.     fonctions K&R.
  103.  
  104.     Une version existe pour MSDOS (PCDOS) version 3 et plus, 
  105.     pour SCO XENIX version 2.3 (UNIX système V.3.2) et pour SUN 
  106.     SPARC (Sunos).
  107.  
  108.     Ce manuel s'applique intégralement dans les trois 
  109.     environnements. Toutefois, le séparateur / a été choisi pour 
  110.     la spécification de fichiers dans le manuel. La version 
  111.     MSDOS du logiciel reconnaît le séparateur \ et non pas /.
  112.  
  113. 1.1      Pourquoi utiliser un extracteur                             
  114.  
  115.     L'utilisation d'un extracteur de prototypes est facultative. 
  116.     On peut inscrire manuellement les prototypes dans un fichier 
  117.     d'inclusion. Le langage ANSI C tolère l'absence de prototype 
  118.     pour conserver une compatibilité avec la version K&R du 
  119.     langage. Le langage C++ commande l'usage de prototypes.
  120.  
  121.     Nous ne tenterons pas de démontrer l'importance des 
  122.     prototypes en programmation. Nous tenterons de démontrer 
  123.     pourquoi une extraction automatique par un outil spécialisé 
  124.     est requise.
  125.  
  126. 1.1.1    Mise en service d'une librairie avec prototypes invalides   
  127.  
  128.     En révisant une librairie, on doit parfois ajouter des 
  129.     fonctions, en éliminer et en modifier. Lorsqu'on livre une 
  130.     nouvelle version d'une librairie, la fiabilité des 
  131.     prototypes est essentielles. Souvent des problèmes avec la 
  132.     nouvelle version seront détectés par une autre équipe de 
  133.     programmeurs, qui seront confondus par le fait que leur 
  134.     projet compile parfaitement mais n'exécute pas bien.
  135.  
  136.     En C ce problème peut prendre un temps considérable à 
  137.     régler. La nouvelle version de la librairie sera la dernière 
  138.     à être soupçonnée. En C++ le problème sera détecté à l'étape 
  139.     du "link". Cela introduira une perte de temps, et surtout 
  140.     une insatisfaction évidente.
  141.  
  142. 1.1.2    Validation implicite du fichier d'inclusion                 
  143.  
  144.     Un truc simple permet de vérifier que les prototypes 
  145.     inscrits dans un fichier d'inclusion sont valides. Il s'agit 
  146.     d'inclure ce fichier dans chacun des sources qui déclarent 
  147.     ces fonctions. Une simple recompilation permettra de 
  148.     comparer les prototypes à la déclaration originale.
  149.  
  150.     Cette méthode a toutefois un lacune. Elle ne détecte pas 
  151.     l'absence d'un prototype, ni ne détecte la présence de 
  152.     prototypes de fonctions périmées.
  153.  
  154.  
  155.  
  156.                                                               1
  157.  
  158.  
  159.     En C++, cette méthode est simplement inutile, car plusieurs 
  160.     fonctions peuvent porter le même nom et posséder des 
  161.     arguments totalement différents.
  162.  
  163. 1.1.3    Révision des clients d'un service                           
  164.  
  165.     On doit parfois modifier les arguments d'une fonction 
  166.     utilisée dans divers autre sous-système. Généralement avant 
  167.     de faire cela, le programmeur localisera toutes les usages 
  168.     de cette fonction et les modifiera en conséquence.
  169.  
  170.     Cela se fera souvent à l'aide du programme GREP. Cette 
  171.     méthode n'est toutefois pas garantie. Il se peut que 
  172.     certains systèmes client soit innaccessibles à GREP (pas sur 
  173.     le même ordinateur), ou simplement inconnus du programmeur.
  174.  
  175.     Notez qu'en C++, la détection des usages d'une fonction 
  176.     membre à l'aide de GREP est pratiquement voué à l'échec. Il 
  177.     faudra utiliser des références croisés ou autre gadgets pour 
  178.     déterminer qui se sert d'une fonction.
  179.  
  180.     Seul une recompilation de ces systèmes clients exposera les 
  181.     utilisations erronés. Cette recompilation pourra se faire 
  182.     plusieurs semaines, et même plusieurs mois après la mise en 
  183.     service de la librairie. La validité des prototypes est la 
  184.     seule assurance.
  185.  
  186. 1.2      Certains compilateurs peuvent extraire les prototypes       
  187.  
  188.     Certains compilateurs ont une option pour extraire les 
  189.     prototypes tout en compilant. Une telle option pose 
  190.     généralement des problèmes de performance et n'est utilisée 
  191.     qu'en dernier recours.
  192.  
  193.     L'extraction des prototypes doit être réalisée avant la 
  194.     compilation; des prototypes valides sont essentiels. Si un 
  195.     compilateur est utilisé, deux sessions de compilation seront 
  196.     nécessaires; une pour extraire les prototypes et une autre 
  197.     pour compiler.
  198.  
  199. 1.2.1    Un compilateur peut oublier des prototypes                  
  200.  
  201.     Si on utilise un compilateur pour extraire des prototypes, 
  202.     on peut se retrouver avec un problème de taille. Le 
  203.     compilateur peut stopper délibérément la compilation d'un 
  204.     source parce qu'ils rencontrent trop d'erreurs. Les 
  205.     prototypes des fonctions qu'il n'a pas compilé ne seront pas 
  206.     générés.
  207.  
  208.     En fait plusieurs des erreurs rencontrés par le compilateur 
  209.     seront causés par l'absence de prototypes valides.
  210.  
  211. 2        Limites de la version d'évaluation                          
  212.  
  213.     Le présent manuel explique toutes les options de 
  214.     l'extracteur.
  215.  
  216.  
  217.  
  218.  
  219.                                                               2
  220.  
  221.  
  222.     Certaines options ne sont pas disponibles dans la version 
  223.     d'évaluation. La licence explique comment on peut obtenir 
  224.     une version complète.
  225.  
  226.     En plus d'obtenir la dernière version du logiciel, l'usager 
  227.     recevra d'autres utilitaires. Ils sont documentés ici. La 
  228.     liste présentée ici est sujet à changement sans préavis.
  229.  
  230. 2.1      Production automatisée de sommaire alphabétique             
  231.  
  232.     Un utilitaire produit un sommaire. Pour chaque fonction, une 
  233.     ligne de commentaires est extraite du source. La ligne 
  234.     choisie est basée sur une convention minimale.
  235.  
  236.     Le fichier produit est un texte dont le format est:
  237.  
  238.       fonction_a: description sommaire de fonction_a
  239.       ...
  240.       fonction_z: description sommaire de fonction_z
  241.  
  242.     La première ligne du bloc de commentaire précédant la 
  243.     déclaration d'une fonction est extraite.
  244.  
  245. 2.2      Production d'un index permuté                               
  246.  
  247.     A partir du sommaire alphabétique, un index basé sur les 
  248.     mots clés de la description est produit. Pour un sommaire 
  249.     comportant les deux fonctions suivantes,
  250.  
  251.       bouton_creation: création et initialisation d'un bouton
  252.       bouton_annule: efface et élimine un bouton de la mémoire
  253.  
  254.     Chacun des mots significatifs de la description seront tour 
  255.     à tour utilisés comme clé de tri. Il devient possible de 
  256.     localiser une fonction en utilisant différents mots clés 
  257.     (efface, élimine, bouton, mémoire, création, ...).
  258.  
  259. 2.3      Production et entretien d'un historique des fonctions       
  260.  
  261.     Un fichier sera entretenu à partir du fichier de prototypes 
  262.     et documentation produit par l'extracteur.
  263.  
  264.     L'historique est un fichier texte. Il contient une 
  265.     description de chaques fonctions accompagnées de sa date de 
  266.     création ou de révision. A chaque fois que le système est 
  267.     révisé, le fichier d'historique est mis à jour en ajoutant 
  268.     les fonctions qui ont été révisées (basé sur une comparaison 
  269.     ASCII du prototype documenté de la fonction), les nouvelles 
  270.     fonctions et en notant les fonctions éliminées.
  271.  
  272.     Ce fichier permet à un programmeur de localiser rapidement 
  273.     les nouveaux services, les services révisés et les services 
  274.     qui ont été éliminés.
  275.  
  276. 3        Spécifications et opération                                 
  277.  
  278.  
  279.  
  280.                                                               3
  281.  
  282.  
  283.     Description des caractéristiques de l'extracteur de 
  284.     prototypes ANSI C. Ce manuel contient un guide d'opération 
  285.     mais aussi des suggestions sur l'application de cet outils.
  286.  
  287. 3.1      Principes généraux                                          
  288.  
  289.     L'extracteur s'applique autant aux projets de quelques 
  290.     fichiers sources qu'aux projets d'envergure: plusieurs 
  291.     centaines de fichiers répartis en plusieurs répertoires.
  292.  
  293. 3.1.1    Systèmes, clients, et fournisseurs en programmation         
  294.  
  295.     Tout au long de ce manuel, nous utiliserons les mots 
  296.     systèmes, clients et fournisseurs.
  297.  
  298.     Un système (package) est une collection de fonctions 
  299.     intimement liées permettant la réalisation d'une tâche 
  300.     spécialisée. Un exemple de système est la série de fonctions 
  301.     str____() livrée avec la majorité des compilateurs C 
  302.     (strcmp, strlen, strcpy, strchr, ...). Ces fonctions 
  303.     proposent généralement un certain nombre de conventions ou 
  304.     modèles à l'usager (le programmeur). Le système est un 
  305.     fournisseur, et les sources qui le composent sont des 
  306.     membres du système.
  307.  
  308.     Le programmeur qui utilise ces fonctions pour réaliser une 
  309.     nouvelle fonction est un client de ce système. Tout au long 
  310.     de ce document, c'est la relation entre ces nouvelles 
  311.     fonctions et les fonctions d'un système qui sera étudiée.
  312.  
  313.     Les fonctions créées à partir d'autres fonctions, sont des 
  314.     clientes. Ces "autres" fonctions sont des fournisseurs. Ces 
  315.     dernières font généralement partie d'un système (parfois 
  316.     appelé librairie).
  317.  
  318. 3.1.2    Déclaration de fonction (prototypes) et définition          
  319.  
  320.     Une différence majeure entre le langage ANSI C et le C 
  321.     original (K&R) est le concept de déclaration de fonction 
  322.     (function prototype). C'est la possibilité de décrire de 
  323.     façon formelle l'interface d'une fonction sans fournir le 
  324.     corps de cette fonction.
  325.  
  326.     Soit la définition de la fonction max():
  327.  
  328.       int max(int a, int b)
  329.       {
  330.           if (a<b) return (b);
  331.           return (a);
  332.       }
  333.  
  334.     Soit la déclaration de la fonction max():
  335.  
  336.       int max (int a, int b);
  337.  
  338.  
  339.  
  340.  
  341.                                                               4
  342.  
  343.  
  344. 3.1.2.1  Utilité des déclarations de fonctions                       
  345.  
  346.     La déclaration d'une fonction permet d'informer le 
  347.     compilateur sur l'interface d'une fonction, sans fournir la 
  348.     fonction au complet. Cela permet de créer une fonction dans 
  349.     un fichier source et de l'utiliser dans un autre en toute 
  350.     sécurité.
  351.  
  352.     Le compilateur aura toutes les informations pour déterminer 
  353.     si l'utilisation (appel de la fonction) faite de cette 
  354.     fonction est conforme. Il pourra vérifier le nombre 
  355.     d'arguments ainsi que le type de chacun. Les appels à la 
  356.     fonction max() seront tous signalés par le compilateur. 
  357.     Evidemment un prototype de la fonction devra être fourni au 
  358.     début du source.
  359.  
  360.       int max(int a, int b);
  361.  
  362.           ...
  363.           char *pt = max ("xyz","zzz");   /* arguments invalides */
  364.           int m = max (1,2,3);            /* nombre d'arguments invalide */
  365.  
  366. 3.1.2.2  Stratégie d'utilisation des prototypes                      
  367.  
  368.     Généralement on placera dans un fichier d'inclusion (*.h) 
  369.     les prototypes de toutes les fonctions composant un système 
  370.     ou librairie. Plusieurs fichiers d'inclusion fournis avec le 
  371.     compilateur que vous utilisez contiennent des prototypes de 
  372.     fonctions.
  373.  
  374.     Les fonctions clientes (utilisant cette librairie) devront 
  375.     inclure ce fichier d'inclusion au début du source.
  376.  
  377.     exemple:
  378.  
  379.       #include <string.h>
  380.  
  381.       ...
  382.       char *pt = strlen("....."); /* strlen() est déclaré dans string.h */
  383.  
  384. 3.1.2.3  Composition du fichier d'inclusion                          
  385.  
  386.     Le fichier d'inclusion associé à un système ne contiendra 
  387.     pas nécessairement les prototypes de toutes les fonctions 
  388.     contenues dans ce système.
  389.  
  390.     Les fonctions "static" ne seront pas incluses, puisqu'elles 
  391.     ne sont pas accessibles. Certaines fonctions internes non 
  392.     plus, puisque souvent, elles ne sont ni documentées, ni 
  393.     utilisables aisément par les sources clients d'une 
  394.     librairie.
  395.  
  396.  
  397.  
  398.  
  399.  
  400.                                                               5
  401.  
  402.  
  403.     Un fichier d'inclusion est donc créé avec le client en tête. 
  404.     Un programmeur peut créer deux fichiers d'inclusion pour un 
  405.     système. Un sera utilisé par les fonctions membres et 
  406.     l'autre par les fonctions clientes. L'extracteur permet de 
  407.     construire sélectivement des fichiers d'inclusion.
  408.  
  409. 3.2      ANSI C et C++ supportés                                     
  410.  
  411.     L'extracteur reconnait la syntaxe C et C++. Aucune option 
  412.     n'est requise. Quelques options permettent de traiter 
  413.     spécifiquement certains déclarations tel les fonctions 
  414.     membres C++.
  415.  
  416. 3.3      Mot-clés ajoutés pour automatiser l'opération de            
  417.          l'extracteur                                                
  418.  
  419.     Le langage C++ ne permet pas d'extraire les prototypes d'une 
  420.     façon complètement automatique. Pour sa part le langage C 
  421.     possède un concept rudimentaire de controle de l'accès.
  422.  
  423.     Sept mot-clés sont interprétés par l'extracteur pour 
  424.     complètement controler la génération des prototypes à partir 
  425.     du source.
  426.  
  427.       export      C et C++
  428.       _export     C et C++
  429.       PRIVATE     C++
  430.       PUBLIC      C++
  431.       PROTECTED   C++
  432.       STATIC      C++
  433.       VIRTUAL     C++
  434.  
  435. 3.3.1    Définition des mots clés supplémentaires                    
  436.  
  437.     Les mots clés export,_export,PRIVATE,PROTECTED,PUBLIC et 
  438.     VIRTUAL ne sont pas supportés par plusieurs compilateurs C 
  439.     et C++. On devra fournir au préprocesseur une définition 
  440.     nulle pour chacun de ces mot-clés.
  441.  
  442.     Un définition nulle peut s'exprimer directement sur la ligne 
  443.     de commande (généralement option -d du compilateur) ou dans 
  444.     un fichier d'inclusion.
  445.  
  446.       #define export
  447.       #define _export
  448.       #define PUBLIC
  449.       #define PRIVATE
  450.       #define PROTECTED
  451.       #define VIRTUAL
  452.  
  453.     Notez que _export est supporté par certain compilateurs.
  454.  
  455. 3.4      Options de la ligne de commande                             
  456.  
  457.  
  458.  
  459.  
  460.  
  461.                                                               6
  462.  
  463.  
  464.     Cette section décrit la liste des options spécifiables sur 
  465.     la ligne de commande. Une option est spécifiée par un '-' 
  466.     suivie d'une lettre suivie optionnellement d'une séquence de 
  467.     caractères non blancs:
  468.  
  469.       -x
  470.       -ceoi
  471.       -ffichier.nar
  472.  
  473. 3.4.1    @fichier : fichier contenant des paramètres de ligne de     
  474.          commande                                                    
  475.  
  476.     Si un paramètre de la ligne de commande débute par @, il 
  477.     sera interprété comme un nom de fichier. Ce fichier 
  478.     contiendra lui-même d'autres paramètres qui seront 
  479.     interprétés.
  480.  
  481.     Le fichier peut être spécifié avec un répertoire ou non. Si 
  482.     le fichier est spécifié avec un répertoire, ce répertoire et 
  483.     ses ancêtres seront utilisés jusqu'à ce que le fichier soit 
  484.     localisé.
  485.  
  486.     Si aucun répertoire n'est spécifié, le répertoire courant 
  487.     sera consulté, et ses ancêtres ensuite.
  488.  
  489.     Ce mécanisme de localisation permet d'écrire un seul fichier 
  490.     qui sera applicable à plusieurs répertoires. Il permet aussi 
  491.     d'écrire un fichier de paramètres qui sera spécifique à un 
  492.     répertoire.
  493.  
  494. 3.4.1.1  Exemple de localisation de fichiers de commandes            
  495.  
  496.     Soit les répertoires:
  497.  
  498.       /usr/prj1/liba
  499.       /usr/prj1/libb
  500.       /usr/prj1/libb/libb0
  501.       /usr/prj1/libb/libb1
  502.       /usr/prj1/libc
  503.       /usr/prj2/liba
  504.       /usr/prj2/libb
  505.       /usr/prj2/libc
  506.  
  507.     Si on créé les fichiers d'option suivants.
  508.  
  509.       /usr/proto.cfg
  510.       /usr/prj1/libb/proto.cfg
  511.       /usr/prj2/libc/proto.cfg
  512.  
  513.     La liste suivante indique quel fichier de commande sera lu 
  514.     si on applique "proto @proto.cfg" dans chaque répertoire.
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.                                                               7
  522.  
  523.  
  524.       /usr/prj1/liba          /usr/proto.cfg
  525.       /usr/prj1/libb/libb0    /usr/prj1/libb/proto.cfg
  526.       /usr/prj1/libb/libb1    /usr/prj1/libb/proto.cfg
  527.       /usr/prj1/libc          /usr/proto.cfg
  528.       /usr/prj2/liba          /usr/proto.cfg
  529.       /usr/prj2/libb          /usr/proto.cfg
  530.       /usr/prj2/libc          /usr/prj2/libc/proto.cfg
  531.       /lib/prjx               ici la variable d'environnement PATH
  532.                               sera consultée pour localiser proto.cfg
  533.                               de la même façon que les programmes
  534.                               sont localisés.
  535.  
  536. 3.4.1.2  @ spécifié sans fichier                                     
  537.  
  538.     Si le caractère @ apparaît seul, le fichier 'proto.cfg' sera 
  539.     cherché par défaut. Il sera cherché dans le répertoire 
  540.     courant. S'il n'est pas trouvé, le répertoire ancêtre sera 
  541.     cherché (..). La recherche se poursuivra jusqu'à la racine 
  542.     du disque.
  543.  
  544.     Lorsque les fichiers proto.cfg requis sont créés et placés 
  545.     aux bons endroits dans un système de répertoire, la commande 
  546.     "proto @" est suffisante pour extraire les prototypes de 
  547.     n'importe quel système.
  548.  
  549. 3.4.2    -a : Accès par défaut au fonctions membres (C++)            
  550.  
  551.     Les fonctions membres (d'une classe) qui ne spécifient pas 
  552.     d'accès seront déclarés "private". L'option -a permet 
  553.     d'enregistrer un comportement différent.
  554.  
  555.       -a0 : private
  556.       -a1 : protected
  557.       -a2 : public
  558.  
  559.     L'accès d'une fonction membre se spécifie à l'aide d'un des 
  560.     mots clés ajoutés PRIVATE, PROTECTED, et PUBLIC.
  561.  
  562. 3.4.3    -b : Mise à jour d'un fichier C++ à partir d'un fichier .pm 
  563.  
  564.     Normalement, proto regroupe tous les prototypes des 
  565.     fonctions membres d'une classe C++ dans un seul fichier 
  566.     (voir -m0+,-m1+ et -c+). Ce fichier porte généralement 
  567.     l'extension ".pm". A partir de ce fichier, les prototypes 
  568.     des fonctions membres sont distribués dans les fichiers qui 
  569.     contiennent les déclarations des classes. L'option -b active 
  570.     cette distribution.
  571.  
  572.     La syntaxe de l'option est:
  573.  
  574.       -bfichier_à_réviser+fichier_pm=fichier_résultat
  575.       -bfichier_à_réviser+fichier_pm
  576.       -bfichier_à_réviser
  577.       -b
  578.  
  579.  
  580.  
  581.                                                               8
  582.  
  583.  
  584.     Si fichier_résultat n'est pas spécifié, fichier_à_réviser 
  585.     sera pris comme source et destination. Si fichier_pm n'est 
  586.     pas spécifié, X.pm sera choisi (X est le nom du répertoire 
  587.     courant). L'option -b sans arguments sera équivalente à 
  588.     -bX.hpp+X.pm où -bX.h+X.pm où X est le nom du répertoire 
  589.     courant. X.h sera utilisé si X.hpp n'existe pas.
  590.  
  591.     L'option -b peut être utilisé plusieurs fois (pour réviser 
  592.     plusieurs fichier d'inclusion) sur la ligne de commande. Son 
  593.     action ne sera déclenchée qu'après l'extraction du dernier 
  594.     prototype.
  595.  
  596. 3.4.3.1  Exemple d'utilisation de l'option -b                        
  597.  
  598.     Soit la commande,
  599.  
  600.       proto -c+ -fx.pm *.c -bfichier1.h+x.pm -bfichier2.h+x.pm
  601.  
  602.     Le fichier x.pm sera produit. Il contiendra tous les 
  603.     prototypes des fonctions membres. Ensuite les fichier 
  604.     "fichier1.h" et "fichier2.h" seront édités et les prototypes 
  605.     seront distribués dans la déclaration des classes dont ils 
  606.     sont membres.
  607.  
  608. 3.4.3.2  Controle de la distribution des prototypes de fonctions     
  609.          membres                                                     
  610.  
  611.     Les prototypes des fonctions membres doivent être distribués 
  612.     à l'intérieur de la définition de la classe dont ils sont 
  613.     membres. L'extracteur utilise une méthode simple pour 
  614.     localiser l'endroit où les prototypes sont placés.
  615.  
  616.     L'extracteur recherche des paires de commentaires de la 
  617.     forme:
  618.  
  619.       /*~PROTOBEG~ NOM_DE_LA_CLASSE */
  620.       /*~PROTOEND~ */
  621.  
  622.     Les commentaires doivent être seuls sur leur ligne 
  623.     respective. Tous ce qui est entre cette paire de 
  624.     commentaires a été placé là par l'extracteur. Le programmeur 
  625.     ne devra rien ajouter entre ces commentaires, puisque 
  626.     l'extracteur annulera le contenu à chaque révision du 
  627.     fichier.
  628.  
  629. 3.4.4    -c : composition de l'extraction                            
  630.  
  631.     PROTO peut extraire plusieurs informations des fichiers 
  632.     sources qu'il traite. Voici la liste des informations qu'il 
  633.     peut extraire avec la lettre qui servira à spécifier ces 
  634.     informations.
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.                                                               9
  643.  
  644.  
  645.       e : Prototypes des fonctions export (extension au langage C).
  646.       o : Prototypes des fonctions ordinaires.
  647.       p : Prototypes des fonctions membres C++ "private".
  648.       r : Prototypes des fonctions membres C++ "protected".
  649.       s : Prototypes des fonctions static.
  650.       u : Prototypes des fonctions membres C++ "public".
  651.  
  652.       + : Prototypes des fonctions membres (C++).
  653.       d : Documentations (commentaires) autour de ces fonctions.
  654.       i : Référence inverse fonction vs source.
  655.  
  656.     La commande "proto -cod *.c" extraira les prototypes avec la 
  657.     documentation qui les accompagne pour tous les fichiers *.c 
  658.     du répertoire courant.
  659.  
  660. 3.4.4.1  Le verbe export : extension au C                            
  661.  
  662.     Le verbe export est un ajout au langage C. A notre 
  663.     connaissance aucun compilateur C ne supporte un tel verbe. 
  664.     Ce verbe est présentement appliqué à la déclaration de 
  665.     fonctions, mais peut aussi s'appliquer à la déclaration de 
  666.     types, de constantes, de variables, etc...
  667.  
  668.     Le verbe export a un usage un peu équivalent au verbe 
  669.     static. Ce dernier restreint la visibilité d'un objet au 
  670.     source où il apparaît. Le verbe export, au contraire, 
  671.     indique que la visibilité d'un objet dépasse le cadre du 
  672.     système où il est défini. Une fonction 'export' est un 
  673.     service officiel offert aux clients. Une fonction ordinaire 
  674.     est local au système et ne doit pas être utilisée 
  675.     directement par une fonction cliente du système.
  676.  
  677. 3.4.4.1.1Ajout du verbe export au langage C                          
  678.  
  679.     En utilisant le préprocesseur, il est possible d'ajouter le 
  680.     verbe export au language. On inscrit simplement la ligne 
  681.     "#define export" dans un fichier d'inclusion. Ce fichier est 
  682.     inclus dans les sources qui font usage du verbe.
  683.  
  684.     On peut aussi définir ce verbe sur la ligne de commande à 
  685.     l'aide de l'option -d du compilateur. La plupart des 
  686.     compilateurs supportent une option -d de la même façon que 
  687.     l'extracteur.
  688.  
  689. 3.4.4.1.2Utilité du verbe export                                     
  690.  
  691.     Bien que non supporté par le compilateur, ce verbe permet de 
  692.     classifier les fonctions d'un système. Cela simplifie la vie 
  693.     des clients à la recherche d'un service. Généralement la 
  694.     liste des fonctions offertes aux clients représente moins de 
  695.     la moitié des fonctions du système. Cela simplifie autant 
  696.     l'usage que l'entretien du système.
  697.  
  698. 3.4.4.1.3Le verbe _export                                            
  699.  
  700.  
  701.  
  702.  
  703.                                                              10
  704.  
  705.  
  706.     Le verbe _export devient une extension populaire au language 
  707.     C. Il facilite la réalisation de librairies dynamiques. Il a 
  708.     sémantiquement le même rôle que le verbe export décris plus 
  709.     haut. Les deux verbes sont accepté comme synonimes.
  710.  
  711. 3.4.4.2  Combinaison de l'option -c et -f dans une seule session     
  712.  
  713.     Les options -c et -f peuvent être spécifiées plusieurs fois 
  714.     sur la ligne de commande.
  715.  
  716.     L'option -c établie une composition de résultat valide pour 
  717.     toutes les options -f qui suivent, et ce jusqu'à la 
  718.     prochaine option -c.
  719.  
  720.     La commande "proto -co -fordin.h -cs -fstatic.h -cod 
  721.     -finfo.h *.c" produira trois fichiers de composition 
  722.     différente. On sauve du temps à générer plusieurs fichiers 
  723.     simultanément.
  724.  
  725. 3.4.4.3  Paramètre 'i' de l'option -c: Référence inverse             
  726.  
  727.     Le paramètre 'i' de l'option -c produit une référence 
  728.     inverse fonction -> sources. D'un format compact, le fichier 
  729.     permet de déterminer le source qui contient la déclaration 
  730.     d'une fonction.
  731.  
  732.     Le fichier est un texte ASCII où chaque ligne a la forme 
  733.     suivante:
  734.  
  735.       longueur!nom_de_la_fonction!source
  736.  
  737.     Les points d'exclamation '!' sont présents dans le fichier, 
  738.     comme séparateur. La longueur est la dimension (en octet) de 
  739.     la ligne. Cette longueur est encodée en un seul octet. Pour 
  740.     ne pas nuire à la nature 'texte' du fichier, la constante 32 
  741.     est ajoutée à cette longueur.
  742.  
  743.     Un format texte a été choisi pour simplifier la réalisation 
  744.     de fonction de recherche. Une telle fonction peut être codée 
  745.     directement à partir du langage macro de certains éditeurs.
  746.  
  747. 3.4.4.4  Paramètre 'd' de l'option -c: Prototypes et documentation   
  748.  
  749.     Le paramètre 'd' commande l'extraction des prototypes ainsi 
  750.     que des commentaires entourant la déclaration de la 
  751.     fonction.
  752.  
  753.     Tous les commentaires contigus qui précèdent immédiatement 
  754.     la déclaration ainsi que tous rencontrés avant la première 
  755.     '{' du corps de la fonction seront extrait et placés avec le 
  756.     prototype.
  757.  
  758.     Le format du fichier produit n'est pas compilable. Ce 
  759.     fichier peut être utilisé comme sommaire d'un système.
  760.  
  761. 3.4.4.5  Corrections au prototypes avant la génération               
  762.  
  763.  
  764.  
  765.                                                              11
  766.  
  767.  
  768.     On peut omettre certaines informations lors de la 
  769.     déclaration d'une fonction. L'extracteur ajoute ce qui 
  770.     manque pour produire un prototype valide.
  771.  
  772. 3.4.4.5.1Fonctions sans type de retour                               
  773.  
  774.     Si une fonction est déclaré sans type, l'extracteur ajoute 
  775.     'int' au prototype. La déclaration suivante:
  776.  
  777.       max(int a, int b){....}
  778.  
  779.     produit le prototype suivant:
  780.  
  781.       int max (int a, int b);
  782.  
  783. 3.4.4.5.2Paramètres sans type                                        
  784.  
  785.     Si un paramètre apparait sans type, le mot-clé 'int' est 
  786.     inséré.
  787.  
  788.     Soit la fonction suivante:
  789.  
  790.       int max (a,b){ ... }
  791.  
  792.     Le prototype produit sera:
  793.  
  794.       int max (int a, int b);
  795.  
  796. 3.4.4.5.3Fonctions sans paramètre                                    
  797.  
  798.     Le mot clé 'void' sera automatiquement inséré dans le 
  799.     prototype d'une fonction sans paramètres, s'il n'est pas 
  800.     déjà présent. La déclaration suivante produit:
  801.  
  802.       int fct (){ ... }
  803.  
  804.     produit:
  805.  
  806.       int fct (void);
  807.  
  808. 3.4.5    -C : Ne traite pas les commentaires imbriqués               
  809.  
  810.     Proto permet les commentaires imbriqués. L'option -C annule 
  811.     ce comportement.
  812.  
  813. 3.4.6    -d : Définition de symbole sur la ligne de commande         
  814.  
  815.     L'option -d permet de définir des symboles du préprocesseur 
  816.     directement sur la ligne de commande.
  817.  
  818.  
  819.  
  820.  
  821.  
  822.                                                              12
  823.  
  824.  
  825.     L'option "-dsymxxx" est équivalente à la ligne "#define 
  826.     symxxx".
  827.  
  828.     L'option "-dsymxxx=yyy" est équivalente à "#define symxxx 
  829.     yyy".
  830.  
  831. 3.4.7    -e : Ferme un fichier résultat                              
  832.  
  833.     L'option -e est utilisée après l'option -f (+f) et termine 
  834.     l'usage de ce fichier comme fichier résultat. Il est donc 
  835.     possible de produire en une seule session plusieurs fichiers 
  836.     qui ont des contenus complètement différents.
  837.  
  838.     Exemple: proto -ffichier1 a*.c -efichier1 -ffichier2 *.c
  839.  
  840.     Ici, "fichier1" ne contiendra que les prototypes de fonction 
  841.     des fichiers "a*.c". "fichier2" contiendra pour sa part 
  842.     toutes les autres fonctions. Si l'option -e n'avait pas été 
  843.     utilisé, "fichier1" contiendrait toutes les fonctions des 
  844.     fichiers "a*.c" en plus de ceux contenus dans "fichier2".
  845.  
  846. 3.4.7.1  Protection contre le double traitement durant une session   
  847.  
  848.     L'extracteur ne retraitera pas deux fois le même fichier 
  849.     lors d'une session. Cela permet de traiter une série de 
  850.     fichier avec une combinaison d'options et de traiter les 
  851.     autres avec une autre combinaison.
  852.  
  853.     La séquence suivante permet d'associer une combinaison 
  854.     spécifique au fichier xyz.c.
  855.  
  856.     proto -option ... -option xyz.c -option ... -option *.c
  857.  
  858.     Bien que *.c inclue xyz.c, celui-ci ne sera pas traité deux 
  859.     fois.
  860.  
  861. 3.4.7.1.1Fichiers sources répartis dans deux répertoires             
  862.  
  863.     Une méthodologie applicable aux projets en groupe permet de 
  864.     sauver de l'espace disque. Souvent les sources d'un projet 
  865.     sont placés dans un répertoire référence. Le programmeur 
  866.     importe dans un répertoire personnel uniquement les sources 
  867.     qu'il modifie. Ce mécanisme est souvent réalisé par 
  868.     l'éditeur qui lit les fichiers dans le répertoire référence 
  869.     et les sauve dans le répertoire personnel lorsque modifiés.
  870.  
  871.     Soit le projet X dont les sources sont placés dans le 
  872.     répertoire /usr/src/x. Soit le programmeur 'prog' qui révise 
  873.     le projet. Les sources sont importés graduellement dans le 
  874.     répertoire /usr/prog/x.
  875.  
  876.     La commande "proto *.c /usr/src/x/*.c" appliquée dans le 
  877.     répertoire /usr/prog/x produira les prototypes du projet X. 
  878.     La protection contre le double traitement est appliquée sur 
  879.     le nom des fichiers et non pas sur l'accès (path).
  880.  
  881. 3.4.8    -f/+f : identification d'un fichier résultat                
  882.  
  883.  
  884.  
  885.                                                              13
  886.  
  887.  
  888.     L'option -f peut être utilisée plusieurs fois sur la ligne 
  889.     de commande. En une seule session, proto peut produire 
  890.     plusieurs fichiers.
  891.  
  892.     L'option est suivi du nom du fichier qui sera produit. 
  893.     L'option -f crée le fichier. L'option +f ajoute à la fin du 
  894.     fichier.
  895.  
  896.     Le nature du fichier créé dépend de la dernière composition 
  897.     établie par l'option -c.
  898.  
  899.     ex : "proto -cos -ffichier.p *.c" produira "fichier.p" avec 
  900.     tous les prototypes des fonctions ordinaires et static du 
  901.     répertoire courant.
  902.  
  903. 3.4.8.1  Combinaison de l'option -c et -f dans une seule session     
  904.  
  905.     Les options -c et -f peuvent être spécifiées plusieurs fois 
  906.     sur la ligne de commande.
  907.  
  908.     L'option -c établie une composition de résultat valide pour 
  909.     toutes les options -f qui suivent, et ce jusqu'à la 
  910.     prochaine option -c.
  911.  
  912.     La commande "proto -co -fordin.h -cs -fstatic.h -cod 
  913.     -finfo.h *.c" produira trois fichiers de composition 
  914.     différente. On sauve du temps à générer plusieurs fichiers 
  915.     simultanément.
  916.  
  917. 3.4.9    -h : fichier de prototypes C++ à décomposer                 
  918.  
  919.     L'option -h commande la décomposition d'un fichier de 
  920.     prototypes C++ contenant des fonctions membres (class 
  921.     member). Autant de fichier que de classes rencontrés seront 
  922.     produits. Le nom de ces fichiers sera obtenu en utilisant le 
  923.     nom de la classe (potentiellement tronqué) suivit de 
  924.     l'extension ".pp".
  925.  
  926.     Ces fichiers pourront être sous-inclus dans les fichiers 
  927.     d'inclusion déclarant les classes.
  928.  
  929.     -h est suivit sans espace par le nom du fichier à 
  930.     décomposer. -h sans argument commande la décomposition du 
  931.     fichier ".pm" ayant le même nom que le répertoire courant.
  932.  
  933.     La décomposition démarera après l'extraction du dernier 
  934.     prototype.
  935.  
  936.     L'option -h peut être utilisé plusieurs fois sur la ligne de 
  937.     commande.
  938.  
  939. 3.4.10   -i : Mode incrémental                                       
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.                                                              14
  949.  
  950.  
  951.     Lorsque l'option -i est spécifiée, proto vérifie si les 
  952.     fichiers à générer existent déjà. Si oui, il les relie. 
  953.     Lorsque vient le temps de générer les prototypes d'un 
  954.     source, il vérifie si ce dernier a changé depuis la dernière 
  955.     génération. Les fichiers produits par proto contiennent la 
  956.     date de chaque fichiers sources. Si les dates sont 
  957.     semblables, le fichier source n'est pas traité.
  958.  
  959.     Cela accélère significativement le traitement.
  960.  
  961. 3.4.11   -I : Répertoire de recherche pour les fichiers d'inclusion  
  962.  
  963.     L'option -I indique la liste des répertoires à consulter 
  964.     pour localiser les fichiers d'inclusion (directive 
  965.     #include).
  966.  
  967.     L'option -I peut apparaître plusieurs fois sur la ligne de 
  968.     commande. On peut spécifier plusieurs répertoires en une 
  969.     seule fois, en séparant ces répertoires avec un ':'.
  970.  
  971.     ex: -I/usr/include:/include <==> -I/usr/include -I/include
  972.  
  973. 3.4.12   -k : Renomme les mot-clés reconnus par l'extracteur         
  974.  
  975.     Certains mot-clés reconnus par l'extracteur ne sont pas 
  976.     supportés par tous les compilateurs (export, PUBLIC, 
  977.     PRIVATE, ...). Le programmeur doit donc fournir une 
  978.     définition nulle au préprocesseur pour que la présence de 
  979.     ces mots clés soit tolérée par le compilateur.
  980.  
  981.     Ces mot-clés peuvent créés des conflits avec des noms de 
  982.     variables ou de type déjà existant. Il est possible de 
  983.     renommer ces mots clés ou simplement d'en annuler le sens 
  984.     vue de l'extrateur.
  985.  
  986.     L'option -kxxx=yyy renomme le mot-clé xxx à yyy. L'option 
  987.     -kxxx annule le mot-clé xxx. L'option -k peut être utilisée 
  988.     plusieurs fois sur la ligne de commande.
  989.  
  990.     Soit l'exemple suivant où le verbe export entre en conflit 
  991.     avec un typedef existant dans le programme. L'option 
  992.     -kexport=EXPORT aura l'effet suivant: L'extracteur ne 
  993.     reconnaitra plus le mot export comme un mot clé, tandis que 
  994.     le mot EXPORT récupérera le rôle attribué normalement au 
  995.     mot-clé export. Ainsi l'énoncé suivant sera acceptable.
  996.  
  997.     EXPORT export *fct (void);
  998.  
  999. 3.4.13   -l : Spécification d'un nom alternatif pour l'option -h     
  1000.  
  1001.     Lors de l'application de l'option -h, tous les fichiers 
  1002.     produits auront un nom composé du nom de la classe suivit de 
  1003.     l'extension .pp. Le nom d'une classe pourra être tronqué 
  1004.     pour satisfaire les limites du système d'exploitation. Il 
  1005.     est possible que deux classes entrent en conflit.
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.                                                              15
  1012.  
  1013.  
  1014.     L'option -l force l'extracteur à utiliser un autre nom. Ce 
  1015.     nom pourra contenir ou pas un extension.
  1016.  
  1017.     Ex: proto -m0+ -lCLASS_SPEC1=class1.pp 
  1018.     -lCLASS_SPEC2=class2.pp *.c -h
  1019.  
  1020.     Les prototypes des fonctions membres de la classe 
  1021.     CLASS_SPEC1 se retrouveront dans class1.pp et ceux de 
  1022.     CLASS_SPEC2 dans class2.pp.
  1023.  
  1024. 3.4.14   -m : Sélectionne une méthodologie particulière              
  1025.  
  1026.     -m0 : méthodologie pour projets à un seul répertoire
  1027.  
  1028.       "proto -m0 *.c" appliqué dans le répertoire X est équivalent à
  1029.       "proto -ceo -fX.p -ceod -fX.nap -ceoi -fX.nar *.c"
  1030.  
  1031.     -m1 : méthodologie pour projets à plusieurs répertoires
  1032.  
  1033.       "proto -m1 *.c" appliqué dans le répertoire X est équivalent à
  1034.       "proto -ceo -fX.p -ce  -f../include/X.p
  1035.           -ceod -fX.nap -ced -f../doc/X.nap
  1036.           -ceoi -fX.nar -cei -f../doc/X.nar *.c"
  1037.  
  1038. 3.4.14.1 Répertoires alternatifs pour l'exportation des fichiers     
  1039.          résultat                                                    
  1040.  
  1041.     Par défaut l'option -m1 exporte vers les répertoires 
  1042.     ../include et ../doc.
  1043.  
  1044.     Si le répertoire ../include n'existe pas, le répertoire ../h 
  1045.     est utilisé. Au moins un des deux répertoires doit exister 
  1046.     pour que l'option -m1 exécute correctement.
  1047.  
  1048. 3.4.15   -o : Nom alternatif pour l'option -m                        
  1049.  
  1050.     L'option -m compose le nom des fichiers resultats à partir 
  1051.     du nom du répertoire courant. L'option -o permet de 
  1052.     spécifier un autre nom
  1053.  
  1054. 3.4.16   -p : Activation de l'extraction pour les fichiers suivants  
  1055.  
  1056.     Cette option est utilisée après l'option -x. Elle réactive 
  1057.     l'extraction des prototypes pour les fichiers suivants.
  1058.  
  1059.     Par défaut, l'extraction est active.
  1060.  
  1061. 3.4.16.1 Exemple d'utilisation des options -x et -p                  
  1062.  
  1063.     Certains fichiers C ne comportent aucun prototypes 
  1064.     intéressants. Certains fichiers sont produit par des 
  1065.     générateurs d'écrans, de rapports, etc ... ne comportent que 
  1066.     des tableaux et constantes. Ces fichiers sont souvent très 
  1067.     gros. Il est intérressant de les éviter lors de l'extraction 
  1068.     dans le simple but de sauver du temps.
  1069.  
  1070.  
  1071.  
  1072.                                                              16
  1073.  
  1074.  
  1075.     Soit les fichiers ecran1.c et ecran2.c que l'on veut éviter. 
  1076.     La commande "proto -x ecran1.c ecran2.c -p *.c" extraira les 
  1077.     prototypes de tous les fichiers sauf ceux-là.
  1078.  
  1079. 3.4.16.2 Protection contre le double traitement durant une session   
  1080.  
  1081.     L'extracteur ne retraitera pas deux fois le même fichier 
  1082.     lors d'une session. Cela permet de traiter une série de 
  1083.     fichier avec une combinaison d'options et de traiter les 
  1084.     autres avec une autre combinaison.
  1085.  
  1086.     La séquence suivante permet d'associer une combinaison 
  1087.     spécifique au fichier xyz.c.
  1088.  
  1089.     proto -option ... -option xyz.c -option ... -option *.c
  1090.  
  1091.     Bien que *.c inclue xyz.c, celui-ci ne sera pas traité deux 
  1092.     fois.
  1093.  
  1094. 3.4.17   -P : activation du préprocesseur                            
  1095.  
  1096.     Normalement proto ne fait pas l'expansion macro. Il ne fait 
  1097.     pas la lecture des fichiers d'inclusion. Cela permet à proto 
  1098.     de régénérer des sources (option -g) et aussi d'extraire les 
  1099.     prototypes très rapidement.
  1100.  
  1101.     Généralement, le fait d'ignorer les commandes du 
  1102.     préprocesseur n'a aucun effet sur les fichiers produits. Il 
  1103.     existe quelques exceptions où le préprocesseur est essentiel 
  1104.     à la compréhension des déclarations.
  1105.  
  1106.     L'option -P active un préprocesseur complet ANSI C 
  1107.     (construit dans PROTO). Les options -I et -d devront être 
  1108.     utilisées en combinaison.
  1109.  
  1110.     L'option -g (régénération du source) perdra toute 
  1111.     signification.
  1112.  
  1113. 3.4.17.1 Traitement des #define même lorsque le préprocesseur n'est  
  1114.          pas actif                                                   
  1115.  
  1116.     Les définitions des commandes #define sont enregistrées même 
  1117.     si l'expansion macro n'est pas actif (option -P). Cela 
  1118.     permet d'évaluer les commandes #if, #ifdef, et #ifndef.
  1119.  
  1120.     Les commandes #undef sont aussi interprétées dans le même 
  1121.     but.
  1122.  
  1123. 3.4.17.2 Traitements des #if, #ifdef, ... sans -P                    
  1124.  
  1125.     Lorsque le préprocesseur n'est pas actif, il n'est pas 
  1126.     toujours possible de sélectionner adéquatement la section de 
  1127.     code à analyser. Comme les fichiers d'inclusion ne sont pas 
  1128.     lus, la valeur des macros (#define) n'est pas toujours 
  1129.     connue. L'option -d permet de définir des macros directement 
  1130.     sur la ligne de commande.
  1131.  
  1132.  
  1133.  
  1134.  
  1135.                                                              17
  1136.  
  1137.  
  1138. 3.4.18   -s : opération silencieuse                                  
  1139.  
  1140.     Normalement proto présente un rapport pour chaque fichier 
  1141.     produit, indiquant la composition (option -c) en vigueur 
  1142.     pour ce fichier.
  1143.  
  1144.     L'option -s rend proto silencieux.
  1145.  
  1146. 3.4.19   -t : lecture du source à traiter sur la console             
  1147.  
  1148.     L'option -t force proto à lire un source sur l'entrée 
  1149.     standard (généralement la console). Cela permet de faire des 
  1150.     tests rapidement.
  1151.  
  1152.     La commande "proto -cxxxx -t" permet de vérifier le 
  1153.     comportement de proto pour certaines combinaisons.
  1154.  
  1155. 3.4.20   -v : Liste des fichiers traités                             
  1156.  
  1157.     L'option -v commande l'affichage de tous les fichiers 
  1158.     traités par proto.
  1159.  
  1160. 3.4.21   -x : exclusion d'un groupe de fichier                       
  1161.  
  1162.     Tous les fichiers spécifiés après l'option -x seront exclus 
  1163.     du traitement. L'option -p renverse cet état.
  1164.  
  1165.     la commande "proto -x xxxx.c -p *.c" génère les prototypes 
  1166.     de tous les fichiers *.c sauf le fichier xxxx.c.
  1167.  
  1168. 3.4.21.1 Exemple d'utilisation des options -x et -p                  
  1169.  
  1170.     Certains fichiers C ne comportent aucun prototypes 
  1171.     intéressants. Certains fichiers sont produit par des 
  1172.     générateurs d'écrans, de rapports, etc ... ne comportent que 
  1173.     des tableaux et constantes. Ces fichiers sont souvent très 
  1174.     gros. Il est intérressant de les éviter lors de l'extraction 
  1175.     dans le simple but de sauver du temps.
  1176.  
  1177.     Soit les fichiers ecran1.c et ecran2.c que l'on veut éviter. 
  1178.     La commande "proto -x ecran1.c ecran2.c -p *.c" extraira les 
  1179.     prototypes de tous les fichiers sauf ceux-là.
  1180.  
  1181. 3.4.21.2 Protection contre le double traitement durant une session   
  1182.  
  1183.     L'extracteur ne retraitera pas deux fois le même fichier 
  1184.     lors d'une session. Cela permet de traiter une série de 
  1185.     fichier avec une combinaison d'options et de traiter les 
  1186.     autres avec une autre combinaison.
  1187.  
  1188.     La séquence suivante permet d'associer une combinaison 
  1189.     spécifique au fichier xyz.c.
  1190.  
  1191.     proto -option ... -option xyz.c -option ... -option *.c
  1192.  
  1193.     Bien que *.c inclue xyz.c, celui-ci ne sera pas traité deux 
  1194.     fois.
  1195.  
  1196.  
  1197.  
  1198.                                                              18
  1199.  
  1200.  
  1201. 3.4.22   Macros et Caractères spéciaux                               
  1202.  
  1203.     Certains caractères et combinaisons de caractères auront une 
  1204.     interprétation particulière. Cela permettra de créer des 
  1205.     commandes générales dans des fichiers batch.
  1206.  
  1207. 3.4.22.1 $ : Nom du répertoire courant                               
  1208.  
  1209.     Le nom du répertoire courant est régulièrement utilisé pour 
  1210.     composer des noms de fichier ou de répertoire. Certaines 
  1211.     méthodologies spécifient que les prototypes d'un répertoire 
  1212.     doivent être placés dans un fichier portant le nom de ce 
  1213.     répertoire plus une extension.
  1214.  
  1215.     Si on veut créer une commande générale, on doit pouvoir 
  1216.     automatisé la génération du nom.
  1217.  
  1218.     Le caractère $ dans la ligne de commande sera remplacé par 
  1219.     le nom du répertoire courant.
  1220.  
  1221.     "proto -co -f$.p -cod -f$.nap -coi -f$.nar *.c" sera 
  1222.     équivalent à "proto -m0 *.c".
  1223.  
  1224. 3.5      Combinaisons invalides d'options                            
  1225.  
  1226.     Plusieurs options sont disponibles sur la ligne de commande. 
  1227.     Plusieurs combinaisons n'ont aucun sens.
  1228.  
  1229.     Certaines combinaisons invalides sont détectées et un 
  1230.     message d'erreur est spécifié. Certaines combinaisons 
  1231.     généreront des résultats complètement inutiles.
  1232.  
  1233. 3.6      Stratégie d'utilisation de l'extracteur                     
  1234.  
  1235.     L'utilisation de l'extracteur de prototypes est relativement 
  1236.     simple. On applique proto sur un certain nombre de fichier 
  1237.     source et on obtient un ou plusieurs fichier d'inclusion.
  1238.  
  1239.     Beaucoup d'efforts ont été faits pour conserver à proto un 
  1240.     caractère général. Le nombre d'options disponibles en est un 
  1241.     témoin.
  1242.  
  1243.     Nous allons suggérer une approche fonctionnelle applicable 
  1244.     autant au petit projet (1 seul répertoire de source) qu'à un 
  1245.     projet plus important.
  1246.  
  1247. 3.6.1    Convention d'utilisation: Avertissement au lecteur          
  1248.  
  1249.     Les conventions qui suivent ne sont pas absolues. Nous les 
  1250.     jugeons acceptables et pratiques. Ces conventions 
  1251.     proviennent de l'expérience tirée de plusieurs projets de 
  1252.     diverses dimensions.
  1253.  
  1254.     Les suggestions et améliorations sont bienvenues.
  1255.  
  1256. 3.6.2    Le répertoire (directory) est la base de l'organisation d'un
  1257.          système                                                     
  1258.  
  1259.  
  1260.  
  1261.                                                              19
  1262.  
  1263.  
  1264.     Un système est généralement composé de plusieurs sources (10 
  1265.     @ 30). Un système complexe peut être composé de plusieurs 
  1266.     répertoires. En fait ce système est composé de 
  1267.     sous-systèmes.
  1268.  
  1269.     Vu d'un client, un système qu'il soit complexe ou pas, 
  1270.     provient d'un seul répertoire. En fait, un client ne doit 
  1271.     pas savoir si un système est complexe ou pas.
  1272.  
  1273.     Nous proposons donc qu'un répertoire corresponde à un 
  1274.     système. A ce répertoire sera associé une librairie (*.lib) 
  1275.     et un fichier d'inclusion.
  1276.  
  1277. 3.6.3    Convention de noms pour les fichiers d'inclusion            
  1278.  
  1279.     Dans un but de simplicité d'utilisation et de réalisation 
  1280.     nous proposons une convention pour sélectionner le nom des 
  1281.     fichiers d'inclusion.
  1282.  
  1283.     Le nom du répertoire sera choisi comme base du nom des 
  1284.     fichiers d'inclusion. Pour un système placé dans un 
  1285.     répertoire X, le nom des fichiers d'inclusions seront "X.*".
  1286.  
  1287.     Cette convention vise les fichiers qui sont offert aux 
  1288.     systèmes clients.
  1289.  
  1290. 3.6.4    Fichiers générés localement                                 
  1291.  
  1292.     L'option -m0 permet de générer localement 3 fichiers. Pour 
  1293.     un répertoire X, les fichier X.p, X.nap et X.nar. L'option 
  1294.     -m1 génère les mêmes fichiers en plus d'exporter trois 
  1295.     autres.
  1296.  
  1297.     X.p contient les prototypes. Ce fichier sera sous-inclus par 
  1298.     le fichier X.h à l'aide de la commande '#include "X.p"'. Les 
  1299.     prototypes sont placés normalement directement dans le 
  1300.     fichier X.h. Ce fichier contient en plus des prototypes, 
  1301.     diverses définitions et déclarations. Comme l'extracteur ne 
  1302.     peut pas produire les prototypes directement dans X.h sans 
  1303.     en détruire le contenu, un autre fichier doit être produit 
  1304.     et inclus dans X.h.
  1305.  
  1306. 3.6.5    Fichiers exportés pour les clients                          
  1307.  
  1308.     L'option -m1 exporte trois fichiers en plus de produire 
  1309.     trois fichiers localement. Pour un répertoire X, un fichier 
  1310.     X.p sera produit dans le répertoire ../include et les 
  1311.     fichiers X.nap et X.nai seront produit dans le répertoire 
  1312.     ../doc. En fait, ces fichiers portent les mêmes noms que les 
  1313.     fichiers produits localement. Ce sont des versions 
  1314.     restreintes (elles contiennent moins de fonctions) des 
  1315.     fichiers locaux.
  1316.  
  1317.     L'utilisation du verbe 'export' au début de la déclaration 
  1318.     d'une fonction permet de spécifier les fonctions qui doivent 
  1319.     être offertes aux clients.
  1320.  
  1321.  
  1322.  
  1323.  
  1324.                                                              20
  1325.  
  1326.  
  1327. 3.6.5.1  Le verbe export : extension au C                            
  1328.  
  1329.     Le verbe export est un ajout au langage C. A notre 
  1330.     connaissance aucun compilateur C ne supporte un tel verbe. 
  1331.     Ce verbe est présentement appliqué à la déclaration de 
  1332.     fonctions, mais peut aussi s'appliquer à la déclaration de 
  1333.     types, de constantes, de variables, etc...
  1334.  
  1335.     Le verbe export a un usage un peu équivalent au verbe 
  1336.     static. Ce dernier restreint la visibilité d'un objet au 
  1337.     source où il apparaît. Le verbe export, au contraire, 
  1338.     indique que la visibilité d'un objet dépasse le cadre du 
  1339.     système où il est défini. Une fonction 'export' est un 
  1340.     service officiel offert aux clients. Une fonction ordinaire 
  1341.     est local au système et ne doit pas être utilisée 
  1342.     directement par une fonction cliente du système.
  1343.  
  1344. 3.6.6    Unicité du fichier d'inclusion                              
  1345.  
  1346.     Pour un répertoire X, il existe un fichier X.h. Tous les 
  1347.     sources du répertoire X l'inclue. Ce fichier incluant 
  1348.     lui-même X.p, tous les sources ont accès aux prototypes de 
  1349.     toutes les fonctions du répertoire X. Le fichier X.h 
  1350.     contient l'énoncé '#include "X.p"'.
  1351.  
  1352.     Si le répertoire X est un sous-système, le fichier X.h ou 
  1353.     une portion de celui-ci est exporté dans le répertoire 
  1354.     ../include. Il devient disponible aux systèmes clients. 
  1355.     Lorsque qu'un source d'un système client inclut 
  1356.     ../include/X.h, celui-ci inclut ../include/X.p.
  1357.  
  1358.     Les clients ont accès aux prototypes de toutes les fonctions 
  1359.     'export' du système X. De plus, les fichier ../doc/X.nap et 
  1360.     ../doc/X.nai peuvent être consultés pour obtenir plus 
  1361.     d'information sur le système X.
  1362.  
  1363.     Le fichier X.h conceptuellement unique offre une vision 
  1364.     différente aux clients et aux sources du répertoire X.
  1365.